home *** CD-ROM | disk | FTP | other *** search
/ Sprite 1984 - 1993 / Sprite 1984 - 1993.iso / man / lib.fmt / tcl / CrtCommand.man < prev    next >
Encoding:
Text File  |  1992-06-11  |  8.6 KB  |  199 lines
  1.  
  2.  
  3.  
  4. Tcl_CreateCommand     C Library Procedures      Tcl_CreateCommand
  5.  
  6.  
  7.  
  8. _________________________________________________________________
  9.  
  10. NNAAMMEE
  11.      Tcl_CreateCommand, Tcl_DeleteCommand -  define  application-
  12.      specific command bindings
  13.  
  14. SSYYNNOOPPSSIISS
  15.      ##iinncclluuddee <<ttccll..hh>>
  16.  
  17.      TTccll__CCrreeaatteeCCoommmmaanndd(_i_n_t_e_r_p, _c_m_d_N_a_m_e, _p_r_o_c, _c_l_i_e_n_t_D_a_t_a, _d_e_l_e_t_e_P_r_o_c)
  18.  
  19.      int
  20.      TTccll__DDeelleetteeCCoommmmaanndd(_i_n_t_e_r_p, _c_m_d_N_a_m_e)
  21.  
  22. AARRGGUUMMEENNTTSS
  23.      Tcl_Interp          *_i_n_t_e_r_p           (in)      Interpreter
  24.                                                      in  which to
  25.                                                      create   new
  26.                                                      command.
  27.  
  28.      char                *_c_m_d_N_a_m_e          (in)      Name of com-
  29.                                                      mand      to
  30.                                                      create    or
  31.                                                      delete.
  32.  
  33.      Tcl_CmdProc         *_p_r_o_c             (in)      Implementation
  34.                                                      of  new com-
  35.                                                      mand:   _p_r_o_c
  36.                                                      will      be
  37.                                                      called when-
  38.                                                      ever _c_m_d_N_a_m_e
  39.                                                      is   invoked
  40.                                                      as   a  com-
  41.                                                      mand.
  42.  
  43.      ClientData          _c_l_i_e_n_t_D_a_t_a        (in)      Arbitrary
  44.                                                      one-word
  45.                                                      value     to
  46.                                                      pass to _p_r_o_c
  47.                                                      and
  48.                                                      _d_e_l_e_t_e_P_r_o_c.
  49.  
  50.      Tcl_CmdDeleteProc   *_d_e_l_e_t_e_P_r_o_c       (in)      Procedure to
  51.                                                      call  before
  52.                                                      _c_m_d_N_a_m_e   is
  53.                                                      deleted from
  54.                                                      the   inter-
  55.                                                      preter;
  56.                                                      allows   for
  57.                                                      command-
  58.                                                      specific
  59.                                                      cleanup.  If
  60.  
  61.  
  62.  
  63. Sprite v1.0                                                     1
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. Tcl_CreateCommand     C Library Procedures      Tcl_CreateCommand
  71.  
  72.  
  73.  
  74.                                                      NULL,   then
  75.                                                      no procedure
  76.                                                      is    called
  77.                                                      before   the
  78.                                                      command   is
  79.                                                      deleted.
  80. _________________________________________________________________
  81.  
  82.  
  83. DDEESSCCRRIIPPTTIIOONN
  84.      TTccll__CCrreeaatteeCCoommmmaanndd defines a new command in _i_n_t_e_r_p and  asso-
  85.      ciates  it with procedure _p_r_o_c such that whenever _c_m_d_N_a_m_e is
  86.      invoked as a Tcl command (via a call to  TTccll__EEvvaall)  the  Tcl
  87.      interpreter will call _p_r_o_c to process the command.  If there
  88.      is already a command  _c_m_d_N_a_m_e  associated  with  the  inter-
  89.      preter,  it  is  deleted.   _P_r_o_c  should  have arguments and
  90.      result that match the type TTccll__CCmmddPPrroocc:
  91.           typedef int Tcl_CmdProc(
  92.                ClientData _c_l_i_e_n_t_D_a_t_a,
  93.                Tcl_Interp *_i_n_t_e_r_p,
  94.                int _a_r_g_c,
  95.                char *_a_r_g_v[]);
  96.      When _p_r_o_c is invoked the _c_l_i_e_n_t_D_a_t_a  and  _i_n_t_e_r_p  parameters
  97.      will  be copies of the _c_l_i_e_n_t_D_a_t_a and _i_n_t_e_r_p arguments given
  98.      to TTccll__CCrreeaatteeCCoommmmaanndd.  Typically, _c_l_i_e_n_t_D_a_t_a  points  to  an
  99.      application-specific  data  structure that describes what to
  100.      do when the command procedure is  invoked.   _A_r_g_c  and  _a_r_g_v
  101.      describe  the  arguments  to  the  command,  _a_r_g_c giving the
  102.      number of arguments (including the command  name)  and  _a_r_g_v
  103.      giving  the  values  of  the arguments as strings.  The _a_r_g_v
  104.      array will contain _a_r_g_c+1  values;  the  first  _a_r_g_c  values
  105.      point to the argument strings, and the last value is NULL.
  106.  
  107.      _P_r_o_c must return an integer  code  that  is  either  TTCCLL__OOKK,
  108.      TTCCLL__EERRRROORR,  TTCCLL__RREETTUURRNN, TTCCLL__BBRREEAAKK, or TTCCLL__CCOONNTTIINNUUEE.  See the
  109.      Tcl overview man page for details on what these codes  mean.
  110.      Most  normal  commands will only return TTCCLL__OOKK or TTCCLL__EERRRROORR.
  111.      In addition, _p_r_o_c must set  _i_n_t_e_r_p->_r_e_s_u_l_t  to  point  to  a
  112.      string value; in the case of a TTCCLL__OOKK return code this gives
  113.      the result of the command, and in the case of  TTCCLL__EERRRROORR  it
  114.      gives  an  error  message.  The TTccll__SSeettRReessuulltt procedure pro-
  115.      vides an easy interface for setting the return  value;   for
  116.      complete details on how the _i_n_t_e_r_p->_r_e_s_u_l_t field is managed,
  117.      see the TTccll__IInntteerrpp man page.  Before invoking a command pro-
  118.      cedure,  TTccll__EEvvaall  sets  _i_n_t_e_r_p->_r_e_s_u_l_t to point to an empty
  119.      string, so simple commands can return  an  empty  result  by
  120.      doing nothing at all.
  121.  
  122.      The contents of the _a_r_g_v array are copies made  by  the  Tcl
  123.      interpreter  for the use of _p_r_o_c.  _P_r_o_c may alter any of the
  124.      strings in _a_r_g_v.  However, the _a_r_g_v  array  is  recycled  as
  125.      soon as _p_r_o_c returns, so _p_r_o_c must not set _i_n_t_e_r_p->_r_e_s_u_l_t to
  126.  
  127.  
  128.  
  129. Sprite v1.0                                                     2
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. Tcl_CreateCommand     C Library Procedures      Tcl_CreateCommand
  137.  
  138.  
  139.  
  140.      point anywhere within the _a_r_g_v  values  (call  Tcl_SetResult
  141.      with  status  TTCCLL__VVOOLLAATTIILLEE  if  you want to return something
  142.      from the _a_r_g_v array).
  143.  
  144.      _D_e_l_e_t_e_P_r_o_c will be invoked when  (if)  _c_m_d_N_a_m_e  is  deleted.
  145.      This  can  occur  through  a  call  to  TTccll__DDeelleetteeCCoommmmaanndd or
  146.      TTccll__DDeelleetteeIInntteerrpp, or by replacing _c_m_d_N_a_m_e in another call to
  147.      Tcl_CreateCommand.  _D_e_l_e_t_e_P_r_o_c is invoked before the command
  148.      is deleted, and gives  the  application  an  opportunity  to
  149.      release   any   structures   associated  with  the  command.
  150.      _D_e_l_e_t_e_P_r_o_c should have arguments and result that  match  the
  151.      type TTccll__CCmmddDDeelleetteePPrroocc:
  152.  
  153.           typedef void Tcl_CmdDeleteProc(ClientData _c_l_i_e_n_t_D_a_t_a);
  154.  
  155.      The _c_l_i_e_n_t_D_a_t_a argument will be the same as  the  _c_l_i_e_n_t_D_a_t_a
  156.      argument passed to TTccll__CCrreeaatteeCCoommmmaanndd.
  157.  
  158.      TTccll__DDeelleetteeCCoommmmaanndd deletes a command from  a  command  inter-
  159.      preter.  Once the call completes, attempts to invoke _c_m_d_N_a_m_e
  160.      in _i_n_t_e_r_p will result in errors.  If _c_m_d_N_a_m_e isn't bound  as
  161.      a  command in _i_n_t_e_r_p then TTccll__DDeelleetteeCCoommmmaanndd does nothing and
  162.      returns -1;  otherwise it returns 0.  There are no  restric-
  163.      tions  on  _c_m_d_N_a_m_e:   it may refer to a built-in command, an
  164.      application-specific command, or a Tcl procedure.
  165.  
  166.  
  167. KKEEYYWWOORRDDSS
  168.      bind, command, create, delete, interpreter
  169.  
  170.  
  171.  
  172.  
  173.  
  174.  
  175.  
  176.  
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195. Sprite v1.0                                                     3
  196.  
  197.  
  198.  
  199.